HR REST API Dokümantasyonu

SetUser

Bu doküman, Synergy’de İnsan Kaynakları modülünde yer alan kullanıcıların REST API üzerinden yönetilmesi için geliştirilen SetUser endpoint’inin çalışma mantığını tanımlamaktadır.

Upsert Mantığı

SetUser fonksiyonu upsert (insert veya update) mantığıyla çalışır:

1. İlgili kullanıcı sistemde yoksa kayıt oluşturulur (INSERT).
2. İlgili kullanıcı sistemde varsa mevcut kayıt güncellenir (UPDATE).

Veri kontrolü, her nesneye özgü benzersiz kod alanı üzerinden yapılır. Kullanıcı için bu alan username bilgisidir.

---

Endpoint Referansı

SetUser — Kullanıcı Oluşturma/Güncelleme

POST User/SetUser

Kullanıcı oluşturur veya günceller.

Anahtar alan: username

İstek Gövdesi (Request Body)

İstek gövdesi, hrObject anahtarı altında kullanıcı bilgilerini içeren bir JSON nesnesi olmalıdır.

{
  "hrObject": {
    "username": "jdoe",
    "password": "Acme123",
    "firstName": "John",
    "lastName": "Doe",
    "eMail": "john.doe@acme.com",
    "status": 1,
    "importStatus": 1,
    "defaultCulture": "tr-TR",
    "departmentCode": "it-dept",
    "professionCode": "senior-dev",
    "employmentStart": "2024-12-01",
    "employmentEnd": "2026-12-31",
    "companyCodes": [
      "AcmeCorp",
      "AcmeInt"
    ],
    "sex": 1,
    "category": 1,
    "type": 1,
    "IdentificationNumber": "111231231",
    "RegistrationNumber": "222222",
    "phone": "0200 123 45 67",
    "mobilePhone": "0500 123 45 67",
    "birthDate": "1986-11-04",
    "properties": [
      {
        "code": "prop-text",
        "valueML": {
          "tr-TR": "TR Değer",
          "en-US": "EN Value"
        }
      },
      {
        "code": "prop-list",
        "valueML": {
          "tr-TR": "1"
        }
      }
    ],
    "managers": [
      {
        "managerKeyDescription": "default",
        "managerUserCode": "admin"
      }
    ]
  }
}

Alan Açıklamaları

Alan Adı	Tip	Zorunlu	Açıklama
username	string	Evet	Kullanıcı adı. Upsert işleminin anahtar alanıdır.
password	string	Evet	Kullanıcı şifresi.
firstName	string	Evet	Kullanıcının adı.
lastName	string	Evet	Kullanıcının soyadı.
eMail	string	Evet	Kullanıcının e-posta adresi.
status	integer	Hayır	Kullanıcı durumu. 1: Aktif, 0: Pasif.
importStatus	integer	Hayır	HR Transfer aktarım durumu.
defaultCulture	string	Hayır	Varsayılan dil kodu. Örnek: tr-TR, en-US.
departmentCode	string	Evet	Sistemde tanımlı departman kodu.
professionCode	string	Evet	Sistemde tanımlı unvan kodu.
companyCodes	string[]	Hayır	Kullanıcının atandığı şirket kodları dizisi.
sex	int	Hayır	0: Kadın, 1: Erkek, 2: Diğer, 3: Belirtilmedi.
category	int	Hayır	0: Mavi Yaka, 1: Beyaz Yaka.
type	int	Hayır	0: Normal, 1: Özel.
IdentificationNumber	string	Hayır	Vatandaşlık numarası.
RegistrationNumber	string	Hayır	Sicil numarası.
phone	string	Hayır	Sabit telefon numarası.
mobilePhone	string	Hayır	Cep telefonu numarası.
birthDate	date	Hayır	Doğum tarihi. Örnek: 1986-01-13.
employmentStart	date	Hayır	İşe başlangıç tarihi. Örnek: 2020-01-13.
employmentEnd	date	Hayır	İşten ayrılma tarihi. Örnek: 2026-12-13.
managers	string[]	Hayır	Kullanıcının yönetici anahtarı bazında yönetici dizisi.
properties	string[]	Hayır	Kullanıcı detayında yer alan özellik dizisi.

---

properties Dizisi

Kullanıcıya ait özel alanlar properties dizisi üzerinden tanımlanır. Birden fazla property gönderilebilir.

Alan Adı	Tip	Zorunlu	Açıklama
code	string	Evet	Sistemde tanımlı property kodu.
valueML	object	Evet	Dil-değer çiftlerinden oluşan nesne. Tüm property tipleri bu format üzerinden iletilir. Örnek: { "tr-TR": "değer", "en-US": "value" }.

Property değerleri, veri tipi boolean, string, decimal veya date fark etmeksizin valueML üzerinden dil kodu-değer çifti ile iletilmelidir.

Bu kullanım, property verilerinin veritabanında saklanma yönteminden kaynaklanan bir gerekliliktir.

Zorunlu Property Kontrolü

Yeni kullanıcı oluşturulurken, kullanıcı detayında yer alan zorunlu özellikler kontrol edilir.

Zorunlu özellikler SetUser fonksiyonundaki properties bloğunda yer almıyorsa aşağıdaki gibi bir uyarı mesajı döndürülür:

{
  "success": false,
  "message": "Required properties missing: Prop1, Company, TestList"
}

Property Değerlerinin Silinmesi

Kullanıcı düzenleme işleminde properties bloğu boş bir dizi olarak gönderildiğinde, bu durum kullanıcının özellik verilerinin silinmesi isteği olarak kabul edilir.

{
  "properties": []
}

Not: Kullanıcı detayında zorunlu özellikler varsa değer silme işlemi gerçekleştirilmez. Silinemeyen zorunlu özellikler response mesajında belirtilir.

{
  "success": false,
  "message": "Required properties cannot be cleared: Prop1, Company, TestList"
}

---

managers Dizisi

managers dizisi, kullanıcının yöneticilerini tanımlamak için kullanılır. Birden fazla yönetici anahtarı desteklenir.

Alan Adı	Tip	Zorunlu	Açıklama
managerKeyDescription	string	Evet	Sistemde tanımlı yönetici anahtarının adı. Örnek: default.
managerUserCode	string	Evet	İlgili yönetici anahtarına atanacak kullanıcının sicil numarası.

Yönetici Bilgilerinin Silinmesi

Kullanıcı düzenleme işleminde managers bloğu boş bir dizi olarak gönderildiğinde, bu durum kullanıcıda tanımlı yönetici bilgilerinin silinmesi isteği olarak kabul edilir.

{
  "managers": []
}

---

Örnek Yanıtlar

Başarılı Yanıt — 200 OK

İşlem başarıyla tamamlandığında result alanında oluşturulan veya güncellenen kullanıcının sistemde saklanan ID değeri döndürülür.

{
  "result": 21768,
  "success": true
}

Hata Yanıtı — Yakalanan Doğrulama Hatası

Zorunlu alan eksikliği veya geçersiz değer gibi durumlarda hata, upsert fonksiyonu tarafından yakalanır ve anlaşılır bir mesajla döndürülür.

{
  "success": false,
  "message": "username is required."
}

Hata Yanıtı — Sistem İstisnası (Internal Error)

Tüm hatalar doğrulama düzeyinde yakalanamayabilir. Beklenmeyen sistem hatalarında iç içe exception zinciri döndürülür.

{
  "success": false,
  "message": "Error occured in HumanResourcesAPI.Set...",
  "internalMessage": "Error occured in BaseAPI.SendRequestWithUrl | ...",
  "exception": {
    "ClassName": "...ServiceAPIException",
    "Code": "SAPI_HRA__0001",
    "FootPrint": "77f76fd2a6b4fa6ac5008d6c41e87854",
    "InnerException": {
      "ClassName": "...ServiceAPIException",
      "Code": "SAPI_BASE_0001",
      "InnerException": {
        "...": "..."
      }
    }
  }
}

---

Notlar

1. username alanı, hem oluşturma hem de güncelleme işlemi için anahtar görevi görür. Bu nedenle güncelleme işlemlerinde de mutlaka gönderilmelidir.
2. companyCodes alanı, birden fazla şirket kodunu dizi olarak kabul eder.
3. departmentCode ve professionCode alanları, sistemde önceden tanımlanmış kodlara referans verir.
4. Zorunlu alan kontrolleri sırayla yapılır. Kaydetme işleminde tüm zorunlu alanlar aynı anda kontrol edilerek bir liste halinde döndürülmez.
   • Örneğin hem firstName hem de lastName alanı boş gönderilirse response içerisinde öncelikle firstName alanına ait uyarı gösterilir.
   • Yalnızca properties bloğundaki zorunlu özellikler toplu olarak kontrol edilir ve eksik özellikler liste halinde döndürülür.